docs/development/Hardware Debugging in VSC on Windows 10 or 11 with WSL.md

   1 # Hardware Debugging in Visual Studio Code and WSL
   2
   3 Real debugging makes life easier, here is a configuration for VSCode with WSL for Windows 10/11.
   4
   5 ## Hardware:
   6 For the basics, please read [Hardware Debugging.md](Hardware%20Debugging.md) up to the section "Compilation options", everything after that is outdated.
   7 In contrast to the instructions above, I had to connect the Target VCC pin of my original ST-Link/V2 to the 3.3V of the FC, otherwise I got an error message that the voltage of the target was too low. The FC is not supplied with voltage via this pin, only the voltage of the target is measured to ensure signal compatibility. (See ST-Link/V2 manual, table 4).
   8 Check with "STM32 ST-LINK Utility" if the connection to the FC is working.
   9
  10 ## Software:
  11 Read [IDE - Visual Studio Code with Windows 10.md](IDE%20-%20Visual%20Studio%20Code%20with%20Windows%2010.md) and set up VSCode like this.
  12 I recommend to use WSL2 and to work in the Linux file system (e.g. `~/git/inav`), access to the files in the Linux FS you get
  13 in Windows 10 via `\\wsl$` in the address line of the explorer, in Windows 11 via the new entry "Linux" in the explorer.
  14
  15 "Cortex Debug" is also required as an additional extension for VSCode.
  16
  17 ## OpenOCD
  18 Now we come to the sticking point:
  19 Unfortunately, WSL cannot pass the ST link (or only via tools such as usbipd-win, see the instructions here: [Windows 11 - VS Code - WSL2 - Hardware Debugging.md](Windows%2011%20-%20VS%20Code%20-%20WSL2%20-%20Hardware%20Debugging.md)), so OpenOCD must run on the Windows side, which is no problem since gdb and OpenOCD communicate with each other via TCP.
  20
  21 Tip:
  22 Only for OpenOCD you don't need to install xpm and node.js, just download the archive at https://github.com/xpack-dev-tools/openocd-xpack/releases and unpack it into a folder of your choice.
  23
  24 Now OpenOCD needs board definition files for the FC, the files generated by the makefile do not work for me.
  25 Copy the following files to `scripts\board` in the OpenOCD folder:
  26
  27 f4fc.cfg:
  28 ```
  29 # Boardconfig for ST-Link/V2 with F4-FC
  30
  31 source [find interface/stlink.cfg]
  32
  33 transport select hla_swd
  34
  35 source [find target/stm32f4x.cfg]
  36
  37 reset_config none separate
  38 ```
  39
  40 f7fc.cfg
  41 ```
  42 # Boardconfig for ST-Link/V2 with F7-FC
  43
  44 source [find interface/stlink.cfg]
  45
  46 transport select hla_swd
  47
  48 source [find target/stm32f7x.cfg]
  49
  50 reset_config none separate
  51 ```
  52
  53 h7fc.cfg
  54 ```
  55 # Boardconfig for ST-Link/V2 with H7-FC
  56
  57 source [find interface/stlink.cfg]
  58
  59 transport select hla_swd
  60
  61 source [find target/stm32h7x_dual_bank.cfg]
  62
  63 reset_config none separate
  64 ```
  65
  66 In order for GDB and OpenOCD to be able to communicate with each other, the host (Windows) IP address is required, the easiest and most convenient way is to have this done automatically by the linux bash to do this automatically, add the following line to the `~/.bashrc` file:
  67
  68 `export WSL_HOST_IP=$(cat /etc/resolv.conf | sed -rn 's|nameserver (.*)|\1|p')`
  69
  70 Actually, the trick is quite simple:
  71 In launch.json set `servertype` to `external` and `gdbTarget` to `windows-host-ip:3333`, the .cfg file must of course be passed when starting openOCD in windows and the connection must be bound to 0.0.0.0.
  72
  73 ## VSCode configuration files
  74
  75 For convenience, I have created a set of VSCode configuration files, that do all the magic.
  76 And before anyone asks: Yes, WSL can launch applications on the host.
  77
  78 launch.json
  79 ```
  80 {
  81     "configurations": [
  82       {
  83         "name": "Debug",
  84         "type": "cortex-debug",
  85         "request": "launch",
  86         "servertype": "external",
  87         "cwd": "${workspaceRoot}/debug",
  88         //"runToEntryPoint": "main",
  89         "executable": "${workspaceRoot}/debug/bin/${config:inav.debug.target}.elf",
  90         "gdbTarget": "${config:openocd.host}:3333",
  91         "svdFile": "${workspaceRoot}/dev/svd/${config:inav.debug.svdFile}",
  92         "preLaunchTask": "Debug",
  93         "showDevDebugOutput": "parsed"
  94       },
  95     ],
  96   }
  97 ```
  98
  99 tasks.json
 100 ```
 101 {
 102     "version": "2.0.0",
 103     "tasks": [
 104         {
 105             "label": "Launch OpenOCD",
 106             "command": "${config:openocd.path}",
 107             "args": [
 108                 "-f",
 109                 "\"board/${config:inav.debug.board}\"",
 110                 "-c",
 111                 "\"bindto 0.0.0.0\""
 112             ],
 113             "type": "shell",
 114             "isBackground": false,
 115             "group": "none",
 116             "presentation": {
 117                 "reveal": "always",
 118                 "panel": "new"
 119             },
 120             "problemMatcher": []
 121         },
 122         {
 123             "label": "CMAKE Release",
 124             "type": "shell",
 125             "command": "mkdir -p release && cd release && cmake -DCMAKE_BUILD_TYPE=Release ..",
 126             "group": "build",
 127             "problemMatcher": [],
 128             "options": {
 129                 "cwd": "${workspaceFolder}"
 130             }
 131         },
 132         {
 133             "label": "CMAKE Debug",
 134             "type": "shell",
 135             "command": "mkdir -p debug && cd debug && cmake -DCMAKE_BUILD_TYPE=Debug ..",
 136             "group": "build",
 137             "problemMatcher": [],
 138             "options": {
 139                 "cwd": "${workspaceFolder}"
 140             }
 141         },
 142         {
 143             "label": "CMAKE Build",
 144             "type": "shell",
 145             "command": "mkdir -p build && cd build && cmake ..",
 146             "group": "build",
 147             "problemMatcher": [],
 148             "options": {
 149                 "cwd": "${workspaceFolder}"
 150             }
 151         },
 152         {
 153             "label": "Compile autogenerated docs",
 154             "type": "shell",
 155             "command": "python3 src/utils/update_cli_docs.py",
 156             "problemMatcher": [],
 157             "options": {
 158                 "cwd": "${workspaceFolder}"
 159             }
 160         },
 161         {
 162             "label": "Debug",
 163             "type": "shell",
 164             "command": "make ${config:inav.debug.target}",
 165             "group": "build",
 166             "problemMatcher": [],
 167             "options": {
 168                 "cwd": "${workspaceFolder}/debug"
 169             }
 170         },
 171         {
 172             "label": "Release",
 173             "type": "shell",
 174             "command": "make ${config:inav.release.target}",
 175             "group": "build",
 176             "problemMatcher": [],
 177             "options": {
 178                 "cwd": "${workspaceFolder}/release"
 179             }
 180         },
 181         {
 182             "label": "Build",
 183             "type": "shell",
 184             "command": "make ${config:inav.release.Target}",
 185             "group": "build",
 186             "problemMatcher": [],
 187             "options": {
 188                 "cwd": "${workspaceFolder}/build"
 189             }
 190         },
 191         {
 192             "label": "Clean Debug",
 193             "type": "shell",
 194             "command": "make clean",
 195             "group": "build",
 196             "problemMatcher": [],
 197             "options": {
 198                 "cwd": "${workspaceFolder}/debug"
 199             }
 200         },
 201         {
 202             "label": "Clean Build",
 203             "type": "shell",
 204             "command": "make clean",
 205             "group": "build",
 206             "problemMatcher": [],
 207             "options": {
 208                 "cwd": "${workspaceFolder}/build"
 209             }
 210         },
 211         {
 212             "label": "Clean Release",
 213             "type": "shell",
 214             "command": "make clean",
 215             "group": "build",
 216             "problemMatcher": [],
 217             "options": {
 218                 "cwd": "${workspaceFolder}/release"
 219             }
 220         },
 221     ]
 222 }
 223 ```
 224
 225 settings.json
 226 ```
 227 {
 228     "cortex-debug.armToolchainPath": "${workspaceRoot}/tools/gcc-arm-none-eabi-10-2020-q4-major/bin",
 229     "openocd.host": "${env:WSL_HOST_IP}",
 230     "openocd.path": "/mnt/path/to/openocd/bin/openocd.exe",
 231     "inav.debug.svdFile": "STM32F405.svd",
 232     "inav.debug.target": "OMNIBUSF4SD",
 233     "inav.release.target": "MATEKF722SE",
 234     "inav.debug.board": "f4fc.cfg"
 235 }
 236 ```
 237
 238 Only the settings.json needs to be modified:
 239
 240 | Option | Explanation |
 241 |--------|-------------|
 242 | cortex-debug.armToolchainPath | path to ARM toolchain, e.g. `${workspaceRoot}/tools/gcc-arm-none-eabi-10-2020-q4-major/bin` |
 243 | openocd.host | IP address of the Windows host, if the environment variable was set as above, do not change anything here, otherwise manually enter the IP of the Windows host. |
 244 | openocd.path | Path to OpenOCD in Windows, format `/mnt/[windows-drive-letter]/path/to/openocd.exe`, for example `/mnt/c/openocd-0.11.0-1/bin/openocd.exe`. |
 245 | inav.debug.svdFile | SVD file, accroding to the processor on your board, see `/dev/svd`, for example `STM32F405.svd`. |
 246 | inav.debug.target | Debug target, for example `OMNIBUSF4SD` |
 247 | inav.release.target | Release target, for example `MATEKF722SE` |
 248 | inav.debug.board | cfg file for OpenOCD, matching the processor of the board, e.g. `f4fc.cfg`, see above |
 249
 250 ### Tasks
 251
 252 The following tasks are available
 253 | Task | Description |
 254 |------|-------------|
 255 | Launch OpenOCD | Must be started manually once per session, starts OpenOCD with the correct options. |
 256 | CMAKE Release | Creates a new folder "release", and configures the buildsystem for a real release build in it. |
 257 | CMAKE Debug | Creates a new folder "debug", and configures the buildsystem for a real debug build in it. |
 258 | CMAKE Build | Creates a new folder "build" and configures the buildsystem for the standard build. |
 259 | Compile autogenerated docs | Rebuilds the CLI documentation |
 260 | Debug | Compiles a new debug build for the target specified in inav.debug.target |
 261 | Release | Compiles a new release build for the target specified in inav.release.target. |
 262 | Build | Compiles a new standard build for the target specified in inav.release.target. |
 263 | Clean Debug | Cleans up the debug folder |
 264 | Clean Release | Cleans up the release folder |
 265 | Clean Build | Cleans up the build folder |
 266
 267 With `F5`, a new debug session can be started normally (recompiling if necessary), with `CTRL+SHIFT+B` a build task can be started.
 268
 269 ## Problem solving
 270 If OpenOCD reports an error `Couldn't bind to ...`, it may be that Hyper-V is blocking these ports, see this thread on stackoverflow for solutions:
 271 https://stackoverflow.com/questions/48478869/cannot-bind-to-some-ports-due-to-permission-denied